home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / ACORNUSERS / CBSA / COMPUTER / WIMP2 / Readme < prev    next >
Text File  |  1999-05-19  |  14KB  |  253 lines
  1.  Readme for Wimp2 v0.36
  2.  -=-=-=-=-=-=-=-=-=-=-=
  3.  (C) 1994-1999 N. Douglas
  4.  
  5.  *** This project is dedicated to the memory of my late mother who died ***
  6.  ***                   during its original development                  ***
  7.  
  8.    Welcome to the Wimp enhancer module. Enclosed is a module, Wimp2, which
  9. provides preemptive multitasking facilities for all versions of RISC-OS from
  10. RO2 to RO4. Also enclosed is a Wimp2 task manager, !Wimp2Ctrl, which allows
  11. monitoring and control of Wimp2 tasks (along with a natty CPU usage
  12. indicator).
  13.  
  14.    Also included is the application !Wimp2Demo which demonstrates Wimp2 in
  15. action. Feel free to run as many copies as you like and watch how desktop
  16. speed is unimpaired. BTW, make sure each is loaded in before you run another
  17. - the Wimp_OpenTemplate bug (see below) shows up otherwise.
  18.  
  19.    Also available is a patch (written by Andrew Teirney) which intercepts
  20. normal wimp SWI's and patches them to call Wimp2. This patch application
  21. allows lists of applications that can be patched and those which can't, see
  22. the patch documentation for more details. A link to the patch's website is
  23. available from the Wimp2 website (see below).
  24.  
  25.  History:
  26.  -=-=-=-=
  27.     Many many years ago in 1994 there was born an idea for the regeneration
  28. of RISC-OS called Tornado. This was born out of my discussions on fidonet
  29. with other Acorn enthusiasts about how RO was stagnating and how something
  30. needed to be done. This project generated a huge groundswell of thought and
  31. it featured in Acorn User a number of times.
  32.     However, it became clear to me in 1996 that RISC-OS was beyond salvation,
  33. and there were already far better development systems out there (WinNT).
  34. Hence Tornado was ditched in favour of Tornado II, a portable version of
  35. tornado encompassing the ideas within the original. Development continues on
  36. Tornado II to this day (see http://www.nedprod.com/tornado).
  37.     However, in the christmas of 1996 when a RISC-OS port of Tornado II was
  38. still feasible, I wrote the Tornado II support module (v0.12) and released
  39. this to hensa. I continued its development, including a patch to force all
  40. normal RO tasks to use the new preemptive multitasker, but this was curtailed
  41. by the untimely and sudden death of my mother. Subsequently, the project was
  42. ditched for the remainder of those christmas holidays, and the 1997 holidays
  43. were marred by fiance troubles, and so coming towards the 1998 holidays I
  44. resolved to finish what I had started - now not for Tornado II, but for its
  45. own sake.
  46.  
  47.     Hence, I would like to dedicate this project to the memory of my mother,
  48. who died during its initial creation. May she rest in peace.
  49.  
  50.  Introduction:
  51.  -=-=-=-=-=-=-
  52.     For as long as I can remember, many programmers in the Acorn scene
  53. have said that bringing preemptive multitasking to RISC-OS would require a
  54. complete restructuring of how applications are constructed and hence it was
  55. too great a project for Acorn to consider, and hence they could be forgiven
  56. for not implementing it in new versions of RO. As I said then, and prove now,
  57. that is complete bunkum. The restructuring necessary is minimal, and
  58. multithreading support isn't much harder. It was simply that Acorn management
  59. were incompetent and they dropped the ball and prevented talented Acorn
  60. programmers from keeping the operating system up to date.
  61.  
  62.     Indeed, as shown by the patch by Andrew Teirney, it shouldn't be too hard
  63. to make existing applications fully preempted too, although there are great
  64. benefits to using Wimp2 natively (mainly speed and control and stability).
  65.  
  66.     In addition, it would not require much work to implement memory
  67. protection, ensuring that tasks do not and cannot cause operating system
  68. instability. Why these things have not been implemented in at least RO3.5
  69. never mind RO3.1 I cannot fathom, but it doesn't really matter anymore now
  70. anyway. Acorn is going down the tubes through their own doing, and they have
  71. destroyed a wonderful thing in doing so. The original Archimedes A400 series
  72. running RISC-OS 2 was an incredible sight in its day, and it is a testament
  73. to its programmers that it has lasted so long and far. It is just a shame
  74. that the dream was so spoilt as it was.
  75.  
  76.     However, I and many other Acorn programmers can now thank our Acorn
  77. heritage as we write software for other platforms. I produce software many
  78. other programmers envy, and I can only thank Acorn for this.
  79.  
  80.     This is my belated contribution to the benefit of RISC-OS I promised way
  81. back in 1994 when promising tornado, and it is far less spectacular than that
  82. which I promised, but I hope it will do to some part. I also hope that the
  83. many people who still spit on any mention of my name in the newsgroups will
  84. forgive me for not delivering tornado, and I hope they understand at least
  85. partly why. My apologies go to them and to all Acorn enthusiasts - I let you
  86. down, and I apologise. Maybe if I had come through Phoebe would be selling
  87. many units right now.
  88.  
  89.  How do I use this?
  90.  -=-=-=-=-=-=-=-=-=
  91.     Although there isn't really any software development being done on Acorns
  92. anymore, if you are reading this and are writing something then consider
  93. making it preemptively multitasking. All you have to do is ensure Wimp2 is
  94. loaded (using RMEnsure in your !Run file), and call Wimp2_Initialise instead
  95. of Wimp_Initialise. Call Wimp2_Poll instead of Wimp_Poll, Wimp2_RedrawWindow
  96. instead of Wimp_RedrawWindow or Wimp_UpdateWindow. Call Wimp2_Closedown
  97. instead of Wimp_CloseDown. And oh, you'll need to move your 17,18 & 19
  98. handler into a seperate area so Wimp2 can call it. And that's it - that's all
  99. you need to do - obviously, a great many current applications can be
  100. converted to preemptive multitasking this way.
  101.  
  102. See the file Docs.APIs and !Wimp2Demo for more exact details.
  103.  
  104.  How does it work?
  105.  -=-=-=-=-=-=-=-=-
  106.     Firstly, the standard 1cs resolution timer isn't good enough for
  107. preemptive multitasking - get more than ten tasks and the machine crawls.
  108. Really you need at least millisecond resolution, and this is provided by the
  109. Wimp2 module through Wimp2_ReadMonotonicTime, Wimp2_CallAfter and
  110. Wimp2_StopCallAfter.
  111.     To preempt a task, every 1 millisecond the IOC timer interrupts the ARM
  112. and the Wimp2 timer dispatch code gets called. It calls the preemptor, which
  113. schedules a user mode callback as Wimp_Poll can only be called from user
  114. code. Next time the OS drops into user mode code (eg; out of an interrupt or
  115. SWI), the secondary preemptor is called in Wimp2. This saves out the current
  116. context not preserved by Wimp_Poll (sprite redirection, fp regs etc), and
  117. calls Wimp_Poll. It then restores everything again, schedules another timer
  118. interrupt, and returns control to the task.
  119.     Now all the codes returned by Wimp_Poll are stored in memory, including
  120. any redraw regions, and these are retrieved asynchronously by Wimp2_Poll. If
  121. they are redraws, Wimp2_RedrawWindow is called which suspends preemption and
  122. calls Wimp_UpdateWindow.
  123.     As you may have noticed, only user code is preempted. As a result, things
  124. like file operations still lock up the computer, as do any SWI operations as
  125. these run in supervisor mode and RO wasn't built to have supervisor code
  126. preemptively multitasked (well, much of it wasn't - you'd be surprised at how
  127. much of it actually was - that's how RO3 was going to be! - but that's
  128. another story).
  129.     Also, if your task calls Wimp2_Poll and there are no messages in the
  130. queue, it loses the remainder of its time slice. In addition, if bit 0 is set
  131. in the poll mask, the task will be halted until the next message arrives (ie;
  132. Wimp2_Poll won't return until a message is there for it).
  133.  
  134.     That is pretty much it. The sources are included, examine them for more
  135. detail if you want.
  136.  
  137.  Bugs:
  138.  -=-=-
  139.   * If you mask out return of poll codes 4 and 5, Wimp2 currently returns
  140. code 0 whenever 4 or 5 is returned instead of not returning at all. While I
  141. could fix this, the code in this area is really nasty and TBH, for all those
  142. people who wouldn't notice one way or another, I don't think it's worth it.
  143. Email me if you disagree! (thanks to Simon Birtwistle for this)
  144.  
  145.   * Vector assignments (as in OS_Claim ones) aren't saved or restored. This
  146. is easy through OS_DelinkApplication, but it's also very slow. Since 99% of
  147. tasks don't hook onto vectors, I removed the code.
  148.   * On RO2, ColourTrans gets its palette tables mucked up by the
  149. sprite redirection. A ColourTrans_InvalidateCache fixes this, but slows RO3+,
  150. so I removed it.
  151.   * Wimp2 doesn't reduce its memory allocation at present, only extends it.
  152. Thus some memory may be being wasted.
  153.   * The C debugger doesn't like debugging preempted programs. Recompile Wimp2
  154. with redir% set to false to fix this, but you lose sprite redirection when
  155. you do this.
  156.   * If your task does redirect VDU output, preemption becomes a major
  157. overhead (it's additional to that task's maximum slice). Sorry, but it's RO's
  158. fault, not mine.
  159.   * It would seem (merely from observation) that having Wimp2Ctrl loaded when
  160. loading a new patched program increases vastly the chances of instability. I
  161. don't know why this is (I've tried very hard to find out why), but it's
  162. probably best to not have Wimp2Ctrl loaded when you load a new program.
  163.  
  164.  Features:
  165.  -=-=-=-=-
  166.   * The support module uses dynamic areas when available (eg; through having
  167. a RiscPC or installing DummyDynamicAreas or whatever) but defaults to using
  168. RMA if these aren't available. Luckily most blocks are small so fragmentation
  169. shouldn't be too much of a problem.
  170.   * Works right back to RO2.
  171.   * Multiple clients not a problem.
  172.   * Works perfectly with Basic.
  173.   * Written entirely in lovingly hand-crafted assembler.
  174.   * Correctly preempts tasks using floating-point registers and uses multiple
  175. FP stores and loads when available
  176.   * Saves and restores the current VDU redirection state
  177.   * Patches OS_File to allow preemptively multitasked loads and saves
  178.   * Handles the "reply-before-next-Wimp_Poll" problem elegantly and flexibly
  179. in a number of flexible ways.
  180.   * Adds 1ms interrupt facilities for use by other code if you wish
  181.   * Has variable priorities and monitoring of processor usage
  182.  
  183.  Legal:
  184.  -=-=-=
  185.     See the file Docs.Legal for details. It's essentially the GNU Public
  186. licence, which in a nutshell means you get the sources and can release your
  187. own modifications or improvements. I would appreciate if you would send
  188. updates to the contact email address below so that one consistent copy can be
  189. maintained.
  190.  
  191.  Credits:
  192.  -=-=-=-=
  193.     My indebted thanks go to Andrew Teirney for his patch. He has saved me a
  194. lot of work, did a great job and was a pleasure to work with. Cheers Andrew!
  195.     Thanks also to Andreas Walter for his help with debugging the StrongARM
  196. OS_File patch problem which took so long to get fixed.
  197.  
  198.  The patch:
  199.  -=-=-=-=-=
  200.     Probably what will be of most interest to most Acorn users is the ability
  201. to patch existing Wimp apps to use Wimp2 instead of the Wimp - hence they
  202. become preempted just like Wimp2 tasks.
  203.     It is difficult to say exactly what will work and what will not. Oddly,
  204. it would seem most major applications work fine - Fireworkz is an example.
  205. OTOH, smaller applications can have problems - Creator won't save files. The
  206. patch, and Wimp2, do make assumptions about how RO apps are written, and if
  207. an application doesn't fully conform to those assumptions then strange
  208. behaviour can result. Both me and Andrew have made provisions for "different"
  209. approaches to writing an application, but we cannot cover every possibility.
  210.  
  211.     Probably the most strange behaviour will occur without the use of the
  212. -compatible switch. Not using this switch allows better preemption and less
  213. halts for compatibility purposes, but things like multiple apps loading the
  214. same double-clicked file will happen. Often it is better to put up with these
  215. annoyances in favour of better multitasking - but you can choose to use
  216. -compatibility on an app by app basis.
  217.  
  218.     The most likely general complaint will be "app X goes too slowly". The
  219. default value of 5ms max slice is usually fine, but especially on heavily
  220. loaded machines there may be a problem. If this is a problem, use -maxslice
  221. to increase its priority on startup. A value of 100 is likely to make the app
  222. run as quick as if it weren't being preempted, as theroretically the bigger
  223. the maxslice the more cooperatively multitasked it is being. However you pay
  224. with less fluid multitasking while the app is busy.
  225.  
  226.     Finally, there have been noted problems with the patch. One is the
  227. Wimp_OpenTemplate bug listed above - another one occurs with menus which open
  228. windows - a too many windows error can result. Finally, due to the different
  229. way Wimp2 handles window redraws, some window redraw problems can occur -
  230. drag a window over the corrupted region to fix this.
  231.  
  232.  Contacts:
  233.  -=-=-=-=-
  234.     I now have a permanent website at http://www.nedprod.com (it stands for
  235. ned Productions - that's how to remember it). This should be there for the
  236. foreseeable future. It contains pretty much my entire web presence now, along
  237. with the latest copies of many of my programs.
  238.     The section for this program is at http://www.nedprod.com/programs
  239. /RISC-OS/Wimp2. Email related to Wimp2 should be sent to wimp2@nedprod.com.
  240.  
  241.     A point is support for this software. I don't do Acorn development much
  242. anymore, and while I will reply to any sensible email I won't necessarily
  243. change any code. That's for you to do - that's why you have the sources.
  244. However please email me any updates so a single master copy can be
  245. maintained.
  246.  
  247.  Niall Douglas
  248.  19th May 1999.
  249.  
  250.  Email: wimp2@nedprod.com
  251.  Web:   http://www.nedprod.com/programs/RISC-OS/Wimp2
  252.  
  253.